using Traceability.API.Models;

namespace Traceability.API.Services
{
    /// <summary>
    /// 七牛云服务接口
    /// </summary>
    public interface IQiNiuService
    {
        /// <summary>
        /// 上传文件
        /// </summary>
        /// <param name="file">文件</param>
        /// <param name="key">文件Key(可选，不传则自动生成)</param>
        /// <returns>上传结果</returns>
        Task<QiNiuUploadResponse> UploadFileAsync(IFormFile file, string? key = null);

        /// <summary>
        /// 上传文件流
        /// </summary>
        /// <param name="stream">文件流</param>
        /// <param name="fileName">文件名</param>
        /// <param name="key">文件Key(可选，不传则自动生成)</param>
        /// <returns>上传结果</returns>
        Task<QiNiuUploadResponse> UploadStreamAsync(Stream stream, string fileName, string? key = null);

        /// <summary>
        /// 删除文件
        /// </summary>
        /// <param name="key">文件Key</param>
        /// <returns>删除结果</returns>
        Task<QiNiuDeleteResponse> DeleteFileAsync(string key);

        /// <summary>
        /// 获取上传Token
        /// </summary>
        /// <param name="key">文件Key(可选)</param>
        /// <returns>上传Token</returns>
        QiNiuTokenResponse GetUploadToken(string? key = null);

        /// <summary>
        /// 获取文件访问URL
        /// </summary>
        /// <param name="key">文件Key</param>
        /// <returns>访问URL</returns>
        string GetFileUrl(string key);

        /// <summary>
        /// 验证文件
        /// </summary>
        /// <param name="file">文件</param>
        /// <returns>验证结果</returns>
        (bool IsValid, string Message) ValidateFile(IFormFile file);

        /// <summary>
        /// 生成文件Key
        /// </summary>
        /// <param name="fileName">文件名</param>
        /// <returns>文件Key</returns>
        string GenerateFileKey(string fileName);
    }
}
